home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Mac OS SDK / Dev.CD Jan 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / AIncludes / QD3DRenderer.a < prev    next >
Encoding:
Text File  |  1997-08-12  |  41.0 KB  |  1,293 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        QD3DRenderer.a
  3. ;
  4. ;    Contains:    Q3Renderer types and routines                                          
  5. ;
  6. ;    Version:    Technology:    Quickdraw 3D 1.5.1
  7. ;                Release:    Universal Interfaces 3.0.1
  8. ;
  9. ;    Copyright:    © 1995-1997 by Apple Computer, Inc., all rights reserved.
  10. ;
  11. ;    Bugs?:        Please include the the file and version information (from above) with
  12. ;                the problem description.  Developers belonging to one of the Apple
  13. ;                developer programs can submit bug reports to:
  14. ;
  15. ;                    devsupport@apple.com
  16. ;
  17. ;
  18.     IF &TYPE('__QD3DRENDERER__') = 'UNDEFINED' THEN
  19. __QD3DRENDERER__ SET 1
  20.  
  21.     IF &TYPE('__QD3D__') = 'UNDEFINED' THEN
  22.     include 'QD3D.a'
  23.     ENDIF
  24.     IF &TYPE('__QD3DSET__') = 'UNDEFINED' THEN
  25.     include 'QD3DSet.a'
  26.     ENDIF
  27.     IF &TYPE('__QD3DVIEW__') = 'UNDEFINED' THEN
  28.     include 'QD3DView.a'
  29.     ENDIF
  30.  
  31.     IF TARGET_OS_MAC THEN
  32.     IF &TYPE('__EVENTS__') = 'UNDEFINED' THEN
  33.     include 'Events.a'
  34.     ENDIF
  35.     ENDIF    ; TARGET_OS_MAC
  36. ; ******************************************************************************
  37. ; **                                                                             **
  38. ; **                            User Interface Things                             **
  39. ; **                                                                             **
  40. ; ****************************************************************************
  41.  
  42.     IF TARGET_OS_MAC THEN
  43. ; 
  44. ; *  A callback to an application's event handling code. This is needed to    
  45. ; *  support movable modal dialogs. The dialog's event filter calls this      
  46. ; *  callback with events it does not handle.                                 
  47. ; *  If an application handles the event it should return kQ3True.            
  48. ; *  If the application does not handle the event it must return kQ3False and 
  49. ; *  the dialog's event filter will pass the event to the system unhandled.   
  50. ; 
  51.  
  52. TQ3DialogAnchor            RECORD 0
  53. clientEventHandler         ds.l    1                ; offset: $0 (0)
  54. sizeof                     EQU *                    ; size:   $4 (4)
  55.                         ENDR
  56.     ELSEIF TARGET_OS_WIN32 THEN
  57. TQ3DialogAnchor            RECORD 0
  58. ownerWindow                 ds.l    1                ; offset: $0 (0)
  59. sizeof                     EQU *                    ; size:   $4 (4)
  60.                         ENDR
  61.     ELSE
  62. TQ3DialogAnchor            RECORD 0
  63. notUsed                     ds.l    1                ; offset: $0 (0)        ;  place holder 
  64. sizeof                     EQU *                    ; size:   $4 (4)
  65.                         ENDR
  66.     ENDIF    ; TARGET_OS_WIN32
  67. ; ******************************************************************************
  68. ; **                                                                             **
  69. ; **                            Renderer Functions                                 **
  70. ; **                                                                             **
  71. ; ****************************************************************************
  72.  
  73. ;
  74. ; extern TQ3RendererObject Q3Renderer_NewFromType(TQ3ObjectType rendererObjectType)
  75. ;
  76.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  77.         IMPORT_CFM_FUNCTION Q3Renderer_NewFromType
  78.     ENDIF
  79.  
  80. ;
  81. ; extern TQ3ObjectType Q3Renderer_GetType(TQ3RendererObject renderer)
  82. ;
  83.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  84.         IMPORT_CFM_FUNCTION Q3Renderer_GetType
  85.     ENDIF
  86.  
  87.  
  88.  
  89. ; 
  90. ; *    Non-blocking, flush all buffered graphics to rasterizer. May or
  91. ; *    may not update the draw context.
  92. ; *    
  93. ; *    This function has been replaced by Q3View_Flush
  94. ; 
  95.  
  96. ;
  97. ; extern TQ3Status Q3Renderer_Flush(TQ3RendererObject renderer, TQ3ViewObject view)
  98. ;
  99.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  100.         IMPORT_CFM_FUNCTION Q3Renderer_Flush
  101.     ENDIF
  102.  
  103. ; 
  104. ; *    Blocking, flush all buffered graphics to rasterizer and update
  105. ; *    draw context.
  106. ; *    
  107. ; *    This function has been replaced by Q3View_Sync
  108. ; 
  109.  
  110. ;
  111. ; extern TQ3Status Q3Renderer_Sync(TQ3RendererObject renderer, TQ3ViewObject view)
  112. ;
  113.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  114.         IMPORT_CFM_FUNCTION Q3Renderer_Sync
  115.     ENDIF
  116.  
  117.  
  118.  
  119. ; 
  120. ; *    Q3Renderer_IsInteractive
  121. ; *        Determine if this renderer is intended to be used interactively.
  122. ; 
  123.  
  124. ;
  125. ; extern TQ3Boolean Q3Renderer_IsInteractive(TQ3RendererObject renderer)
  126. ;
  127.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  128.         IMPORT_CFM_FUNCTION Q3Renderer_IsInteractive
  129.     ENDIF
  130.  
  131.  
  132. ; 
  133. ; *    Q3Renderer_HasModalConfigure
  134. ; *        Determine if this renderer has a modal settings dialog.
  135. ; *
  136. ; *    Q3Renderer_ModalConfigure
  137. ; *        Have the renderer pop up a modal dialog box to configure its settings.
  138. ; *    dialogAnchor - is platform specific data passed by the client to support
  139. ; *      movable modal dialogs. 
  140. ; *    MacOS: this is a callback to the calling application's event handler.
  141. ; *      The renderer calls this function with events not handled by the 
  142. ; *      settings dialog. This is necessary in order to support movable modal 
  143. ; *      dialogs. An application's event handler must return kQ3True if it 
  144. ; *      handles the event passed to the callback or kQ3False if not. 
  145. ; *      An application which doesn't want to support a movable modal configure
  146. ; *      dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
  147. ; *    Win32: this is the HWND of the owning window (typically an application's
  148. ; *      main window).
  149. ; *  canceled - returns a boolean inditacating that the user canceled the 
  150. ; *    dialog.
  151. ; *      
  152. ; 
  153.  
  154. ;
  155. ; extern TQ3Boolean Q3Renderer_HasModalConfigure(TQ3RendererObject renderer)
  156. ;
  157.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  158.         IMPORT_CFM_FUNCTION Q3Renderer_HasModalConfigure
  159.     ENDIF
  160.  
  161. ;
  162. ; extern TQ3Status Q3Renderer_ModalConfigure(TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled)
  163. ;
  164.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  165.         IMPORT_CFM_FUNCTION Q3Renderer_ModalConfigure
  166.     ENDIF
  167.  
  168. ; 
  169. ; *    Q3RendererClass_GetNickNameString
  170. ; *        Allows an application to get a renderers name string, the 
  171. ; *        renderer is responsible for storing this in a localizable format
  172. ; *        for example as a resource.  This string can then be used to provide
  173. ; *        a selection mechanism for an application (for example in a menu).
  174. ; *
  175. ; *        If this call returns nil in the supplied string, then the App may 
  176. ; *         choose to use the class name for the renderer.  You should always 
  177. ; *        try to get the name string before using the class name, since the
  178. ; *        class name is not localizable.
  179. ; 
  180.  
  181. ;
  182. ; extern TQ3Status Q3RendererClass_GetNickNameString(TQ3ObjectType rendererClassType, TQ3ObjectClassNameString rendererClassString)
  183. ;
  184.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  185.         IMPORT_CFM_FUNCTION Q3RendererClass_GetNickNameString
  186.     ENDIF
  187.  
  188.  
  189. ; 
  190. ; *    Q3Renderer_GetConfigurationData
  191. ; *        Allows an application to collect private renderer configuration data
  192. ; *      which it will then save. For example in a preference file or in a 
  193. ; *        style template. An application should tag this data with the 
  194. ; *        Renderer's object  name.
  195. ; *    
  196. ; *        if dataBuffer is NULL actualDataSize returns the required size in 
  197. ; *        bytes of a data buffer large enough to store private data. 
  198. ; *
  199. ; *      bufferSize is the actual size of the memory block pointed to by 
  200. ; *        dataBuffer
  201. ; *
  202. ; *        actualDataSize - on return the actual number of bytes written to the 
  203. ; *        buffer or if dataBuffer is NULL the required size of dataBuffer
  204. ; * 
  205. ; 
  206.  
  207. ;
  208. ; extern TQ3Status Q3Renderer_GetConfigurationData(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize)
  209. ;
  210.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  211.         IMPORT_CFM_FUNCTION Q3Renderer_GetConfigurationData
  212.     ENDIF
  213.  
  214. ;
  215. ; extern TQ3Status Q3Renderer_SetConfigurationData(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize)
  216. ;
  217.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  218.         IMPORT_CFM_FUNCTION Q3Renderer_SetConfigurationData
  219.     ENDIF
  220.  
  221.  
  222.  
  223. ; ******************************************************************************
  224. ; **                                                                             **
  225. ; **                        Interactive Renderer Specific Functions                 **
  226. ; **                                                                             **
  227. ; ****************************************************************************
  228.  
  229. ;  CSG IDs attribute 
  230. ;  Object IDs, to be applied as attributes on geometries 
  231. ;  Possible CSG equations 
  232.  
  233. ; typedef long                            TQ3CSGEquation
  234. kQ3CSGEquationAandB                EQU        $88888888
  235. kQ3CSGEquationAandnotB            EQU        $22222222
  236. kQ3CSGEquationAanBonCad            EQU        $2F222F22
  237. kQ3CSGEquationnotAandB            EQU        $44444444
  238. kQ3CSGEquationnAaBorCanB        EQU        $74747474
  239.  
  240. ; typedef long                            TQ3HiddenSurfaceRemovalMode
  241. kQ3HiddenSurfaceRemovalMode_None EQU    0
  242. kQ3HiddenSurfaceRemovalMode_Shallow EQU    1
  243. kQ3HiddenSurfaceRemovalMode_Deep EQU    2
  244. ;
  245. ; extern TQ3Status Q3InteractiveRenderer_SetCSGEquation(TQ3RendererObject renderer, TQ3CSGEquation equation)
  246. ;
  247.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  248.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetCSGEquation
  249.     ENDIF
  250.  
  251. ;
  252. ; extern TQ3Status Q3InteractiveRenderer_GetCSGEquation(TQ3RendererObject renderer, TQ3CSGEquation *equation)
  253. ;
  254.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  255.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetCSGEquation
  256.     ENDIF
  257.  
  258. ;
  259. ; extern TQ3Status Q3InteractiveRenderer_SetPreferences(TQ3RendererObject renderer, long vendorID, long engineID)
  260. ;
  261.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  262.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetPreferences
  263.     ENDIF
  264.  
  265. ;
  266. ; extern TQ3Status Q3InteractiveRenderer_GetPreferences(TQ3RendererObject renderer, long *vendorID, long *engineID)
  267. ;
  268.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  269.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetPreferences
  270.     ENDIF
  271.  
  272. ;
  273. ; extern TQ3Status Q3InteractiveRenderer_SetDoubleBufferBypass(TQ3RendererObject renderer, TQ3Boolean bypass)
  274. ;
  275.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  276.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetDoubleBufferBypass
  277.     ENDIF
  278.  
  279. ;
  280. ; extern TQ3Status Q3InteractiveRenderer_GetDoubleBufferBypass(TQ3RendererObject renderer, TQ3Boolean *bypass)
  281. ;
  282.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  283.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetDoubleBufferBypass
  284.     ENDIF
  285.  
  286. ;
  287. ; extern TQ3Status Q3InteractiveRenderer_SetRAVEContextHints(TQ3RendererObject renderer, unsigned long RAVEContextHints)
  288. ;
  289.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  290.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetRAVEContextHints
  291.     ENDIF
  292.  
  293. ;
  294. ; extern TQ3Status Q3InteractiveRenderer_GetRAVEContextHints(TQ3RendererObject renderer, unsigned long *RAVEContextHints)
  295. ;
  296.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  297.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetRAVEContextHints
  298.     ENDIF
  299.  
  300. ;
  301. ; extern TQ3Status Q3InteractiveRenderer_SetRAVETextureFilter(TQ3RendererObject renderer, unsigned long RAVEtextureFilterValue)
  302. ;
  303.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  304.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_SetRAVETextureFilter
  305.     ENDIF
  306.  
  307. ;
  308. ; extern TQ3Status Q3InteractiveRenderer_GetRAVETextureFilter(TQ3RendererObject renderer, unsigned long *RAVEtextureFilterValue)
  309. ;
  310.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  311.         IMPORT_CFM_FUNCTION Q3InteractiveRenderer_GetRAVETextureFilter
  312.     ENDIF
  313.  
  314.  
  315. ; ******************************************************************************
  316. ; **                                                                             **
  317. ; **                            Renderer View Tools                                 **
  318. ; **                                                                             **
  319. ; **                    You may only call these methods from a plug-in             **
  320. ; **                                                                             **
  321. ; ****************************************************************************
  322.  
  323. ; 
  324. ; *    Call by a renderer to call the user "idle" method, with progress 
  325. ; *    information.
  326. ; *    
  327. ; *    Pass in (view, 0, n) on first call
  328. ; *    Pass in (view, 1..n-1, n) during rendering
  329. ; *    Pass in (view, n, n) upon completion
  330. ; *    
  331. ; *    Note: The user must have supplied an idleProgress method with 
  332. ; *    Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is
  333. ; *    called with no progress data. e.g. the Q3View_SetIdleMethod method
  334. ; *    is called instead. (current and final are ignored, essentially.)
  335. ; *
  336. ; *    Returns kQ3Failure if rendering is cancelled.
  337. ; 
  338.  
  339. ;
  340. ; extern TQ3Status Q3XView_IdleProgress(TQ3ViewObject view, unsigned long current, unsigned long completed)
  341. ;
  342.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  343.         IMPORT_CFM_FUNCTION Q3XView_IdleProgress
  344.     ENDIF
  345.  
  346. ; 
  347. ; *    Called by an asynchronous renderer when it completes a frame.
  348. ; 
  349.  
  350. ;
  351. ; extern TQ3Status Q3XView_EndFrame(TQ3ViewObject view)
  352. ;
  353.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  354.         IMPORT_CFM_FUNCTION Q3XView_EndFrame
  355.     ENDIF
  356.  
  357.  
  358. ; ******************************************************************************
  359. ; **                                                                             **
  360. ; **                            Renderer AttributeSet Tools                         **
  361. ; **                                                                             **
  362. ; **                    You may only call these methods from a plug-in             **
  363. ; **                                                                             **
  364. ; ****************************************************************************
  365.  
  366. ; 
  367. ; *    Faster access to geometry attribute sets.
  368. ; *    
  369. ; *    Returns pointer to INTERNAL data structure for elements and attributes
  370. ; *    in an attributeSet, or NULL if no attribute exists.
  371. ; *    
  372. ; *    For attributes of type kQ3AttributeType..., the internal data structure
  373. ; *    is identical to the data structure used in Q3AttributeSet_Add.
  374. ; 
  375.  
  376. ;
  377. ; extern void *Q3XAttributeSet_GetPointer(TQ3AttributeSet attributeSet, TQ3AttributeType attributeType)
  378. ;
  379.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  380.         IMPORT_CFM_FUNCTION Q3XAttributeSet_GetPointer
  381.     ENDIF
  382.  
  383.  
  384.  
  385. kQ3XAttributeMaskNone            EQU        0
  386. kQ3XAttributeMaskSurfaceUV        EQU        $01
  387. kQ3XAttributeMaskShadingUV        EQU        $02
  388. kQ3XAttributeMaskNormal            EQU        $04
  389. kQ3XAttributeMaskAmbientCoefficient EQU    $08
  390. kQ3XAttributeMaskDiffuseColor    EQU        $10
  391. kQ3XAttributeMaskSpecularColor    EQU        $20
  392. kQ3XAttributeMaskSpecularControl EQU    $40
  393. kQ3XAttributeMaskTransparencyColor EQU    $80
  394. kQ3XAttributeMaskSurfaceTangent    EQU        $0100
  395. kQ3XAttributeMaskHighlightState    EQU        $0200
  396. kQ3XAttributeMaskSurfaceShader    EQU        $0400
  397. kQ3XAttributeMaskCustomAttribute EQU    $80000000
  398. kQ3XAttributeMaskAll            EQU        $800007FF
  399. kQ3XAttributeMaskInherited        EQU        $03FF
  400. kQ3XAttributeMaskInterpolated    EQU        $01FF
  401. ; typedef unsigned long                 TQ3XAttributeMask
  402.  
  403. ;
  404. ; extern TQ3XAttributeMask Q3XAttributeSet_GetMask(TQ3AttributeSet attributeSet)
  405. ;
  406.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  407.         IMPORT_CFM_FUNCTION Q3XAttributeSet_GetMask
  408.     ENDIF
  409.  
  410.  
  411. ; ******************************************************************************
  412. ; **                                                                             **
  413. ; **                            Renderer Draw Context Tools                         **
  414. ; **                                                                             **
  415. ; ****************************************************************************
  416.  
  417.  
  418.  
  419. ;
  420. ; extern TQ3Status Q3XDrawContext_GetDrawRegion(TQ3DrawContextObject drawContext, TQ3XDrawRegion *drawRegion)
  421. ;
  422.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  423.         IMPORT_CFM_FUNCTION Q3XDrawContext_GetDrawRegion
  424.     ENDIF
  425.  
  426.  
  427. ; typedef long                            TQ3XDrawContextValidationMasks
  428. kQ3XDrawContextValidationClearFlags EQU    $00000000
  429. kQ3XDrawContextValidationDoubleBuffer EQU $01
  430. kQ3XDrawContextValidationShader    EQU        $02
  431. kQ3XDrawContextValidationClearFunction EQU $04
  432. kQ3XDrawContextValidationActiveBuffer EQU $08
  433. kQ3XDrawContextValidationInternalOffScreen EQU $10
  434. kQ3XDrawContextValidationPane    EQU        $20
  435. kQ3XDrawContextValidationMask    EQU        $40
  436. kQ3XDrawContextValidationDevice    EQU        $80
  437. kQ3XDrawContextValidationWindow    EQU        $0100
  438. kQ3XDrawContextValidationWindowSize EQU    $0200
  439. kQ3XDrawContextValidationWindowClip EQU    $0400
  440. kQ3XDrawContextValidationWindowPosition EQU $0800
  441. kQ3XDrawContextValidationPlatformAttributes EQU $1000
  442. kQ3XDrawContextValidationForegroundShader EQU $2000
  443. kQ3XDrawContextValidationBackgroundShader EQU $4000
  444. kQ3XDrawContextValidationColorPalette EQU $8000
  445. kQ3XDrawContextValidationAll    EQU        $FFFFFFFF
  446. ; typedef unsigned long                 TQ3XDrawContextValidation
  447.  
  448. ;
  449. ; extern TQ3Status Q3XDrawContext_ClearValidationFlags(TQ3DrawContextObject drawContext)
  450. ;
  451.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  452.         IMPORT_CFM_FUNCTION Q3XDrawContext_ClearValidationFlags
  453.     ENDIF
  454.  
  455. ;
  456. ; extern TQ3Status Q3XDrawContext_GetValidationFlags(TQ3DrawContextObject drawContext, TQ3XDrawContextValidation *validationFlags)
  457. ;
  458.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  459.         IMPORT_CFM_FUNCTION Q3XDrawContext_GetValidationFlags
  460.     ENDIF
  461.  
  462.  
  463. ; ******************************************************************************
  464. ; **                                                                             **
  465. ; **                            Renderer Draw Region Tools                         **
  466. ; **                                                                             **
  467. ; ****************************************************************************
  468.  
  469.  
  470. ; typedef long                            TQ3XDevicePixelType
  471.                                                             ; These do not indicate byte ordering   
  472. kQ3XDevicePixelTypeInvalid        EQU        0                    ; Unknown, un-initialized type     
  473. kQ3XDevicePixelTypeRGB32        EQU        1                    ; Alpha:8 (ignored), R:8, G:8, B:8 
  474. kQ3XDevicePixelTypeARGB32        EQU        2                    ; Alpha:8, R:8, G:8, B:8              
  475. kQ3XDevicePixelTypeRGB24        EQU        3                    ; 24 bits/pixel, R:8, G:8, B:8     
  476. kQ3XDevicePixelTypeRGB16        EQU        4                    ; Alpha:1 (ignored), R:5, G:5, B:5 
  477. kQ3XDevicePixelTypeARGB16        EQU        5                    ; Alpha:1, R:5, G:5, B:5              
  478. kQ3XDevicePixelTypeRGB16_565    EQU        6                    ; 16 bits/pixel, R:5, G:6, B:5     
  479. kQ3XDevicePixelTypeIndexed8        EQU        7                    ; 8-bit color table index             
  480. kQ3XDevicePixelTypeIndexed4        EQU        8                    ; 4-bit color table index             
  481. kQ3XDevicePixelTypeIndexed2        EQU        9                    ; 2-bit color table index             
  482. kQ3XDevicePixelTypeIndexed1        EQU        10                    ; 1-bit color table index             
  483.  
  484. ; typedef long                            TQ3XClipMaskState
  485. kQ3XClipMaskFullyExposed        EQU        0
  486. kQ3XClipMaskPartiallyExposed    EQU        1
  487. kQ3XClipMaskNotExposed            EQU        2
  488. TQ3XColorDescriptor        RECORD 0
  489. redShift                 ds.l    1                ; offset: $0 (0)
  490. redMask                     ds.l    1                ; offset: $4 (4)
  491. greenShift                 ds.l    1                ; offset: $8 (8)
  492. greenMask                 ds.l    1                ; offset: $C (12)
  493. blueShift                 ds.l    1                ; offset: $10 (16)
  494. blueMask                 ds.l    1                ; offset: $14 (20)
  495. alphaShift                 ds.l    1                ; offset: $18 (24)
  496. alphaMask                 ds.l    1                ; offset: $1C (28)
  497. sizeof                     EQU *                    ; size:   $20 (32)
  498.                         ENDR
  499. TQ3XDrawRegionDescriptor RECORD 0
  500. width                     ds.l    1                ; offset: $0 (0)
  501. height                     ds.l    1                ; offset: $4 (4)
  502. rowBytes                 ds.l    1                ; offset: $8 (8)
  503. pixelSize                 ds.l    1                ; offset: $C (12)
  504. pixelType                 ds.l    1                ; offset: $10 (16)
  505. colorDescriptor             ds        TQ3XColorDescriptor ; offset: $14 (20)
  506. bitOrder                 ds.l    1                ; offset: $34 (52)
  507. byteOrder                 ds.l    1                ; offset: $38 (56)
  508. clipMask                 ds.l    1                ; offset: $3C (60)
  509. sizeof                     EQU *                    ; size:   $40 (64)
  510.                         ENDR
  511.  
  512. ; typedef long                            TQ3XDrawRegionServicesMasks
  513. kQ3XDrawRegionServicesNoneFlag    EQU        0
  514. kQ3XDrawRegionServicesClearFlag    EQU        $01
  515. kQ3XDrawRegionServicesDontLockDDSurfaceFlag EQU $02
  516. ; typedef unsigned long                 TQ3XDrawRegionServices
  517.  
  518. ;
  519. ; extern TQ3Status Q3XDrawRegion_GetDeviceScaleX(TQ3XDrawRegion drawRegion, float *deviceScaleX)
  520. ;
  521.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  522.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceScaleX
  523.     ENDIF
  524.  
  525. ;
  526. ; extern TQ3Status Q3XDrawRegion_GetDeviceScaleY(TQ3XDrawRegion drawRegion, float *deviceScaleY)
  527. ;
  528.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  529.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceScaleY
  530.     ENDIF
  531.  
  532.  
  533. ;
  534. ; extern TQ3Status Q3XDrawRegion_GetDeviceOffsetX(TQ3XDrawRegion drawRegion, float *deviceOffsetX)
  535. ;
  536.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  537.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceOffsetX
  538.     ENDIF
  539.  
  540. ;
  541. ; extern TQ3Status Q3XDrawRegion_GetDeviceOffsetY(TQ3XDrawRegion drawRegion, float *deviceOffsetX)
  542. ;
  543.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  544.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceOffsetY
  545.     ENDIF
  546.  
  547.  
  548. ;
  549. ; extern TQ3Status Q3XDrawRegion_GetWindowScaleX(TQ3XDrawRegion drawRegion, float *windowScaleX)
  550. ;
  551.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  552.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowScaleX
  553.     ENDIF
  554.  
  555. ;
  556. ; extern TQ3Status Q3XDrawRegion_GetWindowScaleY(TQ3XDrawRegion drawRegion, float *windowScaleY)
  557. ;
  558.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  559.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowScaleY
  560.     ENDIF
  561.  
  562.  
  563. ;
  564. ; extern TQ3Status Q3XDrawRegion_GetWindowOffsetX(TQ3XDrawRegion drawRegion, float *windowOffsetX)
  565. ;
  566.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  567.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowOffsetX
  568.     ENDIF
  569.  
  570. ;
  571. ; extern TQ3Status Q3XDrawRegion_GetWindowOffsetY(TQ3XDrawRegion drawRegion, float *windowOffsetY)
  572. ;
  573.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  574.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetWindowOffsetY
  575.     ENDIF
  576.  
  577. ;
  578. ; extern TQ3Status Q3XDrawRegion_IsActive(TQ3XDrawRegion drawRegion, TQ3Boolean *isActive)
  579. ;
  580.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  581.         IMPORT_CFM_FUNCTION Q3XDrawRegion_IsActive
  582.     ENDIF
  583.  
  584.  
  585. ;
  586. ; extern TQ3Status Q3XDrawRegion_GetNextRegion(TQ3XDrawRegion drawRegion, TQ3XDrawRegion *nextDrawRegion)
  587. ;
  588.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  589.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetNextRegion
  590.     ENDIF
  591.  
  592. ;  
  593. ; *  One of the next two functions must be called before using a draw region 
  594. ; 
  595.  
  596. ; 
  597. ; *    Use this Start function if double buffering/image access services from the
  598. ; *    Draw Context are not needed, you may still request clear for example
  599. ; 
  600.  
  601. ;
  602. ; extern TQ3Status Q3XDrawRegion_Start(TQ3XDrawRegion drawRegion, TQ3XDrawRegionServices services, TQ3XDrawRegionDescriptor **descriptor)
  603. ;
  604.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  605.         IMPORT_CFM_FUNCTION Q3XDrawRegion_Start
  606.     ENDIF
  607.  
  608. ; 
  609. ; *    Use this Start function if double buffering or image access services from 
  610. ; *  the Draw Context are needed.
  611. ; 
  612.  
  613. ;
  614. ; extern TQ3Status Q3XDrawRegion_StartAccessToImageBuffer(TQ3XDrawRegion drawRegion, TQ3XDrawRegionServices services, TQ3XDrawRegionDescriptor **descriptor, void **image)
  615. ;
  616.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  617.         IMPORT_CFM_FUNCTION Q3XDrawRegion_StartAccessToImageBuffer
  618.     ENDIF
  619.  
  620. ; 
  621. ; *    This function is used to indicate that access to a DrawRegion is ended.
  622. ; 
  623.  
  624. ;
  625. ; extern TQ3Status Q3XDrawRegion_End(TQ3XDrawRegion drawRegion)
  626. ;
  627.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  628.         IMPORT_CFM_FUNCTION Q3XDrawRegion_End
  629.     ENDIF
  630.  
  631. ;
  632. ; extern TQ3Status Q3XDrawRegion_GetDeviceTransform(TQ3XDrawRegion drawRegion, TQ3Matrix4x4 **deviceTransform)
  633. ;
  634.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  635.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetDeviceTransform
  636.     ENDIF
  637.  
  638. ;
  639. ; extern TQ3Status Q3XDrawRegion_GetClipFlags(TQ3XDrawRegion drawRegion, TQ3XClipMaskState *clipMaskState)
  640. ;
  641.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  642.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetClipFlags
  643.     ENDIF
  644.  
  645. ;
  646. ; extern TQ3Status Q3XDrawRegion_GetClipMask(TQ3XDrawRegion drawRegion, TQ3Bitmap **clipMask)
  647. ;
  648.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  649.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetClipMask
  650.     ENDIF
  651.  
  652.     IF TARGET_OS_MAC THEN
  653. ;
  654. ; extern TQ3Status Q3XDrawRegion_GetClipRegion(TQ3XDrawRegion drawRegion, RgnHandle *rgnHandle)
  655. ;
  656.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  657.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetClipRegion
  658.     ENDIF
  659.  
  660. ;
  661. ; extern TQ3Status Q3XDrawRegion_GetGDHandle(TQ3XDrawRegion drawRegion, GDHandle *gdHandle)
  662. ;
  663.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  664.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetGDHandle
  665.     ENDIF
  666.  
  667.     ENDIF    ; TARGET_OS_MAC
  668. ;
  669. ; extern TQ3Status Q3XDrawRegion_GetRendererPrivate(TQ3XDrawRegion drawRegion, void **rendererPrivate)
  670. ;
  671.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  672.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetRendererPrivate
  673.     ENDIF
  674.  
  675. ;
  676. ; extern TQ3Status Q3XDrawRegion_SetRendererPrivate(TQ3XDrawRegion drawRegion, const void *rendererPrivate, TQ3XDrawRegionRendererPrivateDeleteMethod deleteMethod)
  677. ;
  678.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  679.         IMPORT_CFM_FUNCTION Q3XDrawRegion_SetRendererPrivate
  680.     ENDIF
  681.  
  682. ;
  683. ; extern TQ3Status Q3XDrawRegion_SetUseDefaultRendererFlag(TQ3XDrawRegion drawRegion, TQ3Boolean flag)
  684. ;
  685.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  686.         IMPORT_CFM_FUNCTION Q3XDrawRegion_SetUseDefaultRendererFlag
  687.     ENDIF
  688.  
  689. ;
  690. ; extern TQ3Status Q3XDrawRegion_GetUseDefaultRendererFlag(TQ3XDrawRegion drawRegion, TQ3Boolean *useDefaultRenderingFlag)
  691. ;
  692.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  693.         IMPORT_CFM_FUNCTION Q3XDrawRegion_GetUseDefaultRendererFlag
  694.     ENDIF
  695.  
  696.  
  697.  
  698. ; ******************************************************************************
  699. ; **                                                                             **
  700. ; **                            Renderer Class Methods                             **
  701. ; **                                                                             **
  702. ; ****************************************************************************
  703.  
  704. ; 
  705. ; *    Methods from Object
  706. ; *        kQ3XMethodTypeObjectClassRegister
  707. ; *        kQ3XMethodTypeObjectClassUnregister
  708. ; *        kQ3XMethodTypeObjectNew
  709. ; *        kQ3XMethodTypeObjectDelete
  710. ; *        kQ3XMethodTypeObjectRead
  711. ; *        kQ3XMethodTypeObjectTraverse
  712. ; *        kQ3XMethodTypeObjectWrite
  713. ; *        
  714. ; *    Methods from Shared
  715. ; *        kQ3MethodTypeSharedEdited
  716. ; *
  717. ; *    Renderer Methods
  718. ; *    
  719. ; *    The renderer methods should be implemented according to the type
  720. ; *    of renderer being written.
  721. ; *
  722. ; *    For the purposes of documentation, there are two basic types of
  723. ; *    renderers: 
  724. ; *
  725. ; *        Interactive
  726. ; *            Interactive Renderer
  727. ; *            WireFrame Renderer
  728. ; *        
  729. ; *        Deferred
  730. ; *            a ray-tracer
  731. ; *            painter's algorithm renderer (cached in a BSP triangle tree)
  732. ; *            an artistic renderer (simulates a pencil drawing, etc.)
  733. ; *
  734. ; *    The main difference is how each renderer handles incoming state and 
  735. ; *    geometry.
  736. ; *
  737. ; *    An interactive renderer immediately transforms, culls, and shades
  738. ; *    incoming geometry and performs rasterization. For example, in a 
  739. ; *    single-buffered WireFrame renderer, you will see a new triangle
  740. ; *    immediately after Q3Triangle_Draw (if it's visible, of course).
  741. ; *
  742. ; *    A deferred renderer caches the view state and each geometry, 
  743. ; *    converting into any internal queue of drawing commands. Rasterization
  744. ; *    is not actually performed until all data has been submitted.
  745. ; *    
  746. ; *    For example, a ray-tracer may not rasterize anything until the
  747. ; *    end of the rendering loop, or until an EndFrame call is made.
  748. ; 
  749.  
  750.  
  751. ; ******************************************************************************
  752. ; **                                                                             **
  753. ; **                        Renderer User Interface Methods                         **
  754. ; **                                                                             **
  755. ; ****************************************************************************
  756.  
  757. ; 
  758. ; *    kQ3XMethodTypeRendererIsInteractive
  759. ; *    
  760. ; *    There is no actual method with this - the metahandler simply returns
  761. ; *  "(TQ3XFunctionPointer)kQ3True" for this "method" if the renderer is 
  762. ; *  intended to be used in interactive settings, and   
  763. ; *    "(TQ3XFunctionPointer)kQ3False" otherwise. 
  764. ; *  
  765. ; *  If neither value is specified in the metahandler, the renderer 
  766. ; *  is *assumed to be non-interactive*!!!
  767. ; *    
  768. ; *    OPTIONAL
  769. ; 
  770.  
  771.  
  772. kQ3XMethodTypeRendererIsInteractive EQU    'isin'
  773.  
  774. ; 
  775. ; *    TQ3XRendererModalConfigureMethod
  776. ; *    
  777. ; *    This method should pop up a modal dialog to edit the renderer settings 
  778. ; *    found in the renderer private. 
  779. ; *    
  780. ; *    dialogAnchor - is platform specific data passed by the client to support
  781. ; *      movable modal dialogs. 
  782. ; *    MacOS: this is a callback to the calling application's event handler.
  783. ; *      The renderer calls this function with events not handled by the 
  784. ; *      settings dialog. This is necessary in order to support movable modal 
  785. ; *      dialogs. An application's event handler must return kQ3True if it 
  786. ; *      handles the event passed to the callback or kQ3False if not. 
  787. ; *      An application which doesn't want to support a movable modal configure
  788. ; *      dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
  789. ; *      A renderer should implement a non-movable style dialog in that case.
  790. ; *    Win32: this is the HWND of the owning window (typically an application's
  791. ; *      main window).  (Win32 application modal dialogs are always movable.)
  792. ; *  canceled - returns a boolean inditacating that the user canceled the 
  793. ; *    dialog.
  794. ; *    
  795. ; *    OPTIONAL
  796. ; 
  797.  
  798.  
  799. kQ3XMethodTypeRendererModalConfigure EQU 'rdmc'
  800. ; 
  801. ; *    kQ3XMethodTypeRendererGetNickNameString
  802. ; *    
  803. ; *        Allows an application to collect the name of the renderer for
  804. ; *        display in a user interface item such as a menu.
  805. ; *    
  806. ; *        If dataBuffer is NULL actualDataSize returns the required size in 
  807. ; *        bytes of a data buffer large enough to store the renderer name. 
  808. ; *
  809. ; *      bufferSize is the actual size of the memory block pointed to by 
  810. ; *        dataBuffer
  811. ; *
  812. ; *        actualDataSize - on return the actual number of bytes written to the
  813. ; *        buffer or if dataBuffer is NULL the required size of dataBuffer
  814. ; *
  815. ; *    OPTIONAL
  816. ; 
  817.  
  818.  
  819. kQ3XMethodTypeRendererGetNickNameString EQU 'rdns'
  820. ; 
  821. ; *    kQ3XMethodTypeRendererGetConfigurationData
  822. ; *    
  823. ; *        Allows an application to collect private configuration data from the
  824. ; *      renderer which it will then save. For example in a preference file, 
  825. ; *      a registry key (on Windows) or in a style template. An application 
  826. ; *      should tag this data with the renderer's object name.
  827. ; *    
  828. ; *        If dataBuffer is NULL actualDataSize returns the required size in 
  829. ; *        bytes of a data buffer large enough to store private data. 
  830. ; *
  831. ; *      bufferSize is the actual size of the memory block pointed to by 
  832. ; *        dataBuffer
  833. ; *
  834. ; *        actualDataSize - on return the actual number of bytes written to the
  835. ; *        buffer or if dataBuffer is NULL the required size of dataBuffer
  836. ; *
  837. ; *    OPTIONAL
  838. ; 
  839.  
  840.  
  841. kQ3XMethodTypeRendererGetConfigurationData EQU 'rdgp'
  842. ; 
  843. ; *    TQ3XRendererSetConfigurationDataMethod
  844. ; *    
  845. ; *        Allows an application to pass private configuration data which has
  846. ; *         previously  been obtained from a renderer via 
  847. ; *        Q3Renderer_GetConfigurationData. For example in a preference file or 
  848. ; *        in a style template. An application should tag this data with the 
  849. ; *        renderer's object name.
  850. ; *    
  851. ; *      bufferSize is the actual size of the memory block pointed to by 
  852. ; *        dataBuffer
  853. ; *
  854. ; *    OPTIONAL
  855. ; 
  856.  
  857.  
  858. kQ3XMethodTypeRendererSetConfigurationData EQU 'rdsp'
  859. ; ******************************************************************************
  860. ; **                                                                             **
  861. ; **                        Renderer Drawing State Methods                         **
  862. ; **                                                                             **
  863. ; ****************************************************************************
  864.  
  865. ; 
  866. ; *    TQ3RendererStartFrame
  867. ; *    
  868. ; *    The StartFrame method is called first at Q3View_StartRendering
  869. ; *    and should:
  870. ; *        - initialize any renderer state to defaults
  871. ; *        - extract any and all useful data from the drawContext
  872. ; *
  873. ; *    If your renderer passed in kQ3RendererFlagClearBuffer at 
  874. ; *    registration, then it should also:
  875. ; *        - clear the drawContext 
  876. ; *    
  877. ; *        When clearing, your renderer may opt to:
  878. ; *        - NOT clear anything (if you touch every pixel, for example)
  879. ; *        - to clear with your own routine, or
  880. ; *        - to use the draw context default clear method by calling 
  881. ; *        Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of
  882. ; *        any available hardware in the system for clearing.
  883. ; *    
  884. ; *    This call also signals the start of all default submit commands from
  885. ; *    the view. The renderer will receive updates for the default view
  886. ; *    state via its Update methods before StartPass is called.
  887. ; *    
  888. ; *    REQUIRED
  889. ; 
  890.  
  891.  
  892. kQ3XMethodTypeRendererStartFrame EQU    'rdcl'
  893. ; 
  894. ; *    kQ3XMethodTypeRendererStartPass
  895. ; *    TQ3XRendererStartPassMethod
  896. ; *    
  897. ; *    The StartPass method is called during Q3View_StartRendering but after
  898. ; *    the StartFrame command. It should:
  899. ; *        - collect camera and light information
  900. ; *    
  901. ; *    If your renderer supports deferred camera transformation, camera is the
  902. ; *    main camera which will be submitted in the hierarchy somewhere. It
  903. ; *    is never NULL.
  904. ; *
  905. ; *    If your renderer does not support deferred camera transformation, camera
  906. ; *    is the transformed camera.
  907. ; *
  908. ; *    If your renderer supports deferred light transformation, lights will be
  909. ; *    NULL, and will be submitted to your light draw methods instead.
  910. ; *
  911. ; *    This call signals the end of the default update state, and the start of 
  912. ; *  submit commands from the user to the view.
  913. ; *
  914. ; *    REQUIRED
  915. ; 
  916.  
  917.  
  918. kQ3XMethodTypeRendererStartPass    EQU        'rdst'
  919. ; 
  920. ; *    kQ3XMethodTypeRendererFlushFrame
  921. ; *    TQ3XRendererFlushFrameMethod
  922. ; *    
  923. ; *    This call is only implemented by asynchronous renderers.
  924. ; *    
  925. ; *    The FlushFrame method is called between the StartPass and EndPass
  926. ; *    methods and is called when the user wishes to flush any asynchronous
  927. ; *    drawing tasks (which draw to the drawcontext), but does not want 
  928. ; *    to block.
  929. ; *    
  930. ; *    The result of this call is that an image should "eventually" appear
  931. ; *    asynchronously.
  932. ; *    
  933. ; *    For asynchronous rendering, this call is non-blocking.
  934. ; *    
  935. ; *    An interactive renderer should ensure that all received
  936. ; *    geometries are drawn in the image.
  937. ; *    
  938. ; *    An interactive renderer that talks to hardware should force
  939. ; *    the hardware to generate an image.
  940. ; *    
  941. ; *    A deferred renderer should exhibit a similar behaviour,
  942. ; *    though it is not required.  A deferred renderer should spawn
  943. ; *    a process that generates a partial image from the currently
  944. ; *    accumulated drawing state. 
  945. ; *    
  946. ; *    However, for renderers such as ray-tracers which generally are
  947. ; *    quite compute-intensive, FlushFrame is not required and is a no-op.
  948. ; *
  949. ; *    OPTIONAL
  950. ; 
  951.  
  952.  
  953. kQ3XMethodTypeRendererFlushFrame EQU    'rdfl'
  954. ; 
  955. ; *    kQ3XMethodTypeRendererEndPass
  956. ; *    TQ3XRendererEndPassMethod
  957. ; *    
  958. ; *    The EndPass method is called at Q3View_EndRendering and signals
  959. ; *    the end of submit commands to the view.
  960. ; *
  961. ; *    If an error occurs, the renderer should call Q3XError_Post and
  962. ; *    return kQ3ViewStatusError.
  963. ; *    
  964. ; *    If a renderer requires another pass on the renderering data,
  965. ; *    it should return kQ3ViewStatusRetraverse.
  966. ; *    
  967. ; *    If rendering was cancelled, this function will not be called
  968. ; *    and the view will handle returning kQ3ViewStatusCancelled;
  969. ; *    
  970. ; *    Otherwise, your renderer should begin completing the process of 
  971. ; *    generating the image in the drawcontext. If you have buffered
  972. ; *    any drawing data, flush it. RendererEnd should have a similar
  973. ; *    effect as RendererFlushFrame.
  974. ; *    
  975. ; *    If the renderer is synchronous:
  976. ; *        - complete rendering of the entire frame
  977. ; *        if the renderer supports kQ3RendererClassSupportDoubleBuffer
  978. ; *            - Update the front buffer
  979. ; *        else
  980. ; *            - DrawContext will update the front buffer after returning
  981. ; *
  982. ; *    If the renderer is asynchronous
  983. ; *        - spawn rendering thread for entire frame
  984. ; *        if the renderer supports kQ3RendererClassSupportDoubleBuffer,
  985. ; *            - you must eventually update the front buffer asynchronously
  986. ; *        else
  987. ; *            - you must eventually update the back buffer asynchronously
  988. ; *            
  989. ; *    REQUIRED
  990. ; 
  991.  
  992.  
  993. kQ3XMethodTypeRendererEndPass    EQU        'rded'
  994. ; 
  995. ; *    kQ3XMethodTypeRendererEndFrame
  996. ; *    TQ3XRendererEndFrame
  997. ; *    
  998. ; *    This call is only implemented by asynchronous renderers.
  999. ; *
  1000. ; *    The EndFrame method is called from Q3View_Sync, which is
  1001. ; *    called after Q3View_EndRendering and signals that the user
  1002. ; *    wishes to see the completed image and is willing to block.
  1003. ; *    
  1004. ; *    If your renderer supports kQ3RendererFlagDoubleBuffer
  1005. ; *        - update the front buffer completely 
  1006. ; *    else
  1007. ; *        - update the back buffer completely
  1008. ; *
  1009. ; *    This call is equivalent in functionality to RendererFlushFrame
  1010. ; *    but blocks until the image is completed.
  1011. ; *    
  1012. ; *    If no method is supplied, the default is a no-op.
  1013. ; *    
  1014. ; *    NOTE: Registering a method of this type indicates that your renderer will
  1015. ; *    be rendering after Q3View_EndRendering has been called.
  1016. ; *    
  1017. ; *    OPTIONAL
  1018. ; 
  1019.  
  1020.  
  1021. kQ3XMethodTypeRendererEndFrame    EQU        'rdsy'
  1022. ; 
  1023. ; *    The RendererCancel method is called after Q3View_StartRendering
  1024. ; *    and signals the termination of all rendering operations.
  1025. ; *
  1026. ; *    A renderer should clean up any cached data, and cancel all 
  1027. ; *    rendering operations.
  1028. ; *    
  1029. ; *    If called before Q3View_EndRendering, the RendererEnd method
  1030. ; *    is NOT called.
  1031. ; *    
  1032. ; *    If called after Q3View_EndRendering, the renderer should kill
  1033. ; *    any threads and terminate any further rendering.
  1034. ; *    
  1035. ; *    REQUIRED
  1036. ; 
  1037.  
  1038.  
  1039. kQ3XMethodTypeRendererCancel    EQU        'rdab'
  1040. ; ******************************************************************************
  1041. ; **                                                                             **
  1042. ; **                        Renderer DrawContext Methods                         **
  1043. ; **                                                                             **
  1044. ; ****************************************************************************
  1045.  
  1046. ; 
  1047. ; *    kQ3XMethodTypeRendererPush
  1048. ; *    TQ3XRendererPushMethod
  1049. ; *    
  1050. ; *    kQ3XMethodTypeRendererPop
  1051. ; *    TQ3XRendererPopMethod
  1052. ; *    
  1053. ; *    These methods are called whenever the graphics state in the view
  1054. ; *    is pushed or popped. The user may isolate state by calling:
  1055. ; *    
  1056. ; *    Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view);
  1057. ; *    Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view);
  1058. ; *    Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view);
  1059. ; *    Q3Box_Submit(&unitBox, view);
  1060. ; *    Q3TranslateTransform_Submit(&unitVector, view);
  1061. ; *    Q3Push_Submit(view);
  1062. ; *        Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view);
  1063. ; *        Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view);
  1064. ; *        Q3Box_Submit(&unitBox, view);
  1065. ; *    Q3Pop_Submit(view);    
  1066. ; *    Q3TranslateTransform_Submit(&unitVector, view);
  1067. ; *    Q3Box_Submit(&unitBox, view);
  1068. ; *    
  1069. ; *    or by submitting a display group which pushes and pops.
  1070. ; *    
  1071. ; *    If you support RendererPush and RendererPop in your renderer:
  1072. ; *        - you must maintain your drawing state as a stack, as well.
  1073. ; *        - you will not be updated with the popped state after
  1074. ; *            RendererPop is called.
  1075. ; *
  1076. ; *    If you do not support Push and Pop in your renderer:
  1077. ; *        - you may maintain a single copy of the drawing state.
  1078. ; *        - you will be updated with changed fields after the view stack is
  1079. ; *            popped.
  1080. ; *
  1081. ; *    A renderer that supports Push and Pop gets called in the following
  1082. ; *    sequence (from example above):
  1083. ; *    
  1084. ; *    RendererUpdateAttributeDiffuseColor(&red,...)
  1085. ; *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1086. ; *    RendererUpdateAttributeSpecularColor(&white,...)
  1087. ; *    RendererUpdateMatrixLocalToWorld(...)
  1088. ; *    RendererSubmitGeometryBox(...)
  1089. ; *    RendererPush(...)
  1090. ; *        RendererUpdateAttributeDiffuseColor(&blue,...)
  1091. ; *        RendererUpdateAttributeTransparencyColor(&green,...)
  1092. ; *        RendererSubmitGeometryBox(...)
  1093. ; *    RendererPop(...)
  1094. ; *    RendererUpdateMatrixLocalToWorld(...)
  1095. ; *    RendererSubmitGeometryBox(...)
  1096. ; *
  1097. ; *    A renderer that does not supports Push and Pop gets called in the
  1098. ; *    following sequence:
  1099. ; *    
  1100. ; *    RendererUpdateAttributeDiffuseColor(&red,...)
  1101. ; *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1102. ; *    RendererUpdateAttributeSpecularColor(&white,...)
  1103. ; *    RendererUpdateMatrixLocalToWorld(...)
  1104. ; *    RendererSubmitGeometryBox(...)
  1105. ; *        RendererUpdateAttributeDiffuseColor(&blue,...)
  1106. ; *        RendererUpdateAttributeTransparencyColor(&green,...)
  1107. ; *        RendererSubmitGeometryBox(...)
  1108. ; *    RendererUpdateAttributeDiffuseColor(&red,...)
  1109. ; *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1110. ; *    RendererUpdateMatrixLocalToWorld(...)
  1111. ; *    RendererSubmitGeometryBox(...)
  1112. ; *    
  1113. ; 
  1114.  
  1115.  
  1116. kQ3XMethodTypeRendererPush        EQU        'rdps'
  1117.  
  1118. kQ3XMethodTypeRendererPop        EQU        'rdpo'
  1119. ; ******************************************************************************
  1120. ; **                                                                             **
  1121. ; **                            Renderer Cull Methods                             **
  1122. ; **                                                                             **
  1123. ; ****************************************************************************
  1124.  
  1125. ; 
  1126. ; *    kQ3XMethodTypeRendererIsBoundingBoxVisible
  1127. ; *    TQ3XRendererIsBoundingBoxVisibleMethod
  1128. ; *    
  1129. ; *    This method is called to cull complex groups and geometries 
  1130. ; *    given their bounding box in local space.
  1131. ; *    
  1132. ; *    It should transform the local-space bounding box coordinates to
  1133. ; *    frustum space and return a TQ3Boolean return value indicating
  1134. ; *    whether the box appears within the viewing frustum.
  1135. ; *    
  1136. ; *    If no method is supplied, the default behavior is to return
  1137. ; *    kQ3True.
  1138. ; *    
  1139. ; 
  1140.  
  1141.  
  1142. kQ3XMethodTypeRendererIsBoundingBoxVisible EQU 'rdbx'
  1143.  
  1144. ; ******************************************************************************
  1145. ; **                                                                             **
  1146. ; **                        Renderer Object Support Methods                         **
  1147. ; **                                                                             **
  1148. ; ****************************************************************************
  1149.  
  1150. ; 
  1151. ; *    Drawing methods (Geometry, Camera, Lights)
  1152. ; *
  1153. ; 
  1154.  
  1155. ; 
  1156. ; *    Geometry MetaHandler
  1157. ; *    
  1158. ; *    This metaHandler is required to support 
  1159. ; *    
  1160. ; *    kQ3GeometryTypeTriangle
  1161. ; *    kQ3GeometryTypeLine
  1162. ; *    kQ3GeometryTypePoint
  1163. ; *    kQ3GeometryTypeMarker
  1164. ; *    kQ3GeometryTypePixmapMarker
  1165. ; *    
  1166. ; *    REQUIRED
  1167. ; 
  1168.  
  1169.  
  1170. kQ3XMethodTypeRendererSubmitGeometryMetaHandler EQU 'rdgm'
  1171. ; 
  1172. ; *    The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType
  1173. ; *    of kQ3GeometryTypeFoo and returns methods of type:
  1174. ; 
  1175.  
  1176. ; 
  1177. ; *    Camera MetaHandler
  1178. ; *    
  1179. ; *    This metaHandler, if supplied, indicates that your renderer
  1180. ; *    handles deferred transformation of the main camera within a scene.
  1181. ; *    
  1182. ; *    If not supplied, or an unsupported camera is used, the view will do
  1183. ; *    the transformation for the renderer and pass in a camera in the 
  1184. ; *    StartPass method.
  1185. ; *    
  1186. ; *    OPTIONAL
  1187. ; 
  1188.  
  1189.  
  1190. kQ3XMethodTypeRendererSubmitCameraMetaHandler EQU 'rdcm'
  1191. ; 
  1192. ; *    The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType
  1193. ; *    of kQ3CameraTypeFoo and returns methods of type:
  1194. ; 
  1195.  
  1196. ; 
  1197. ; *    Light MetaHandler
  1198. ; *    
  1199. ; *    This metaHandler, if supplied, indicates that your renderer
  1200. ; *    handles deferred transformation of lights within a scene.
  1201. ; *    
  1202. ; *    If an unsupported light is encountered, it is ignored.
  1203. ; *
  1204. ; *    OPTIONAL
  1205. ; 
  1206.  
  1207.  
  1208. kQ3XMethodTypeRendererSubmitLightMetaHandler EQU 'rdlg'
  1209. ; 
  1210. ; *    The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType
  1211. ; *    of kQ3LightTypeFoo and returns methods of type:
  1212. ; 
  1213.  
  1214. ; 
  1215. ; *
  1216. ; *    Update methods
  1217. ; *
  1218. ; *    They are called whenever the state has changed. If the renderer supports
  1219. ; *    the RendererPush and RendererPop methods, it must maintain its own state
  1220. ; *    stack. Updates are not called for changed data when the view stack is
  1221. ; *    popped.
  1222. ; *
  1223. ; *    See the comments for the RendererPush and RendererPop methods above
  1224. ; *    for an example of how data is updated.
  1225. ; *
  1226. ; 
  1227.  
  1228. ; 
  1229. ; *    Style
  1230. ; 
  1231.  
  1232.  
  1233. kQ3XMethodTypeRendererUpdateStyleMetaHandler EQU 'rdyu'
  1234. ; 
  1235. ; *    The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType
  1236. ; *    of kQ3StyleTypeFoo and returns methods of type:
  1237. ; 
  1238.  
  1239. ; 
  1240. ; *    Attributes
  1241. ; 
  1242.  
  1243.  
  1244. kQ3XMethodTypeRendererUpdateAttributeMetaHandler EQU 'rdau'
  1245. ; 
  1246. ; *    The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType
  1247. ; *    of kQ3AttributeTypeFoo and returns methods of type:
  1248. ; 
  1249.  
  1250. ; 
  1251. ; *    Shaders
  1252. ; 
  1253.  
  1254.  
  1255. kQ3XMethodTypeRendererUpdateShaderMetaHandler EQU 'rdsu'
  1256. ; 
  1257. ; *    The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType
  1258. ; *    of kQ3ShaderTypeFoo and returns methods of type:
  1259. ; 
  1260.  
  1261. ; 
  1262. ; *    Matrices
  1263. ; 
  1264.  
  1265.  
  1266. kQ3XMethodTypeRendererUpdateMatrixMetaHandler EQU 'rdxu'
  1267. ; typedef TQ3XMetaHandler                 TQ3XRendererUpdateMatrixMetaHandlerMethod
  1268.  
  1269. ; 
  1270. ; *    The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods
  1271. ; *    of the form kQ3MethodTypeRendererUpdateMatrixFoo:
  1272. ; 
  1273.  
  1274.  
  1275. kQ3XMethodTypeRendererUpdateMatrixLocalToWorld EQU 'ulwx'
  1276.  
  1277. kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse EQU 'ulwi'
  1278.  
  1279. kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose EQU 'ulwt'
  1280.  
  1281. kQ3XMethodTypeRendererUpdateMatrixLocalToCamera EQU 'ulcx'
  1282.  
  1283. kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum EQU 'ulfx'
  1284.  
  1285. kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum EQU 'uwfx'
  1286. ; 
  1287. ; *    and returns methods of type:
  1288. ; 
  1289.  
  1290.  
  1291.     ENDIF ; __QD3DRENDERER__ 
  1292.  
  1293.